home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 1.iso
/
ARGONET
/
PD
/
PROGRAMMING
/
PERL.SPK
/
Perl5001
/
Perl
< prev
next >
Wrap
Text File
|
1992-09-11
|
56KB
|
1,925 lines
A P Oliver
11 Sept 92
This file is in the public domain.
Please notify aoliver@acorn.co.uk
of any errors or omissions.
%accept
Not implemented under RISC OS
%alarm
Not implemented under RISC OS
%bind
Not implemented under RISC OS
%binmode
Not implemented under RISC OS
%chmod
Not implemented under RISC OS
%chown
Not implemented under RISC OS
%chroot
Not implemented under RISC OS
%connect
Not implemented under RISC OS
%crypt
Not implemented under RISC OS
%dump
Not implemented under RISC OS
%fcntl
Not implemented under RISC OS
%fileno
Not implemented under RISC OS
%flock
Not implemented under RISC OS
%fork
Not implemented under RISC OS
%getgrent
Not implemented under RISC OS
%setgrent
Not implemented under RISC OS
%endgrent
Not implemented under RISC OS
%getgrgid
Not implemented under RISC OS
%getgrnam
Not implemented under RISC OS
%gethostbyaddr
Not implemented under RISC OS
%gethostbyname
Not implemented under RISC OS
%gethostent
Not implemented under RISC OS
%getlogin
Not implemented under RISC OS
%getnetbyaddr
Not implemented under RISC OS
%getnetbyname
Not implemented under RISC OS
%getnetent
Not implemented under RISC OS
%getpeername
Not implemented under RISC OS
%getpgrp
Not implemented under RISC OS
%getppid
Not implemented under RISC OS
%getpriority
Not implemented under RISC OS
%getprotobyname
Not implemented under RISC OS
%getprotobynumber
Not implemented under RISC OS
%getprotoent
Not implemented under RISC OS
%getpwent
Not implemented under RISC OS
%getpwnam
Not implemented under RISC OS
%getpwuid
Not implemented under RISC OS
%getservbyname
Not implemented under RISC OS
%getservbyport
Not implemented under RISC OS
%getservent
Not implemented under RISC OS
%getsockname
Not implemented under RISC OS
%getsockopt
Not implemented under RISC OS
%ioctl
Not implemented under RISC OS
%semctl
Not implemented under RISC OS
%semget
Not implemented under RISC OS
%semop
Not implemented under RISC OS
%send
Not implemented under RISC OS
%setgrp
Not implemented under RISC OS
%setpriority
Not implemented under RISC OS
%setsockopt
Not implemented under RISC OS
%shmctl
Not implemented under RISC OS
%shmget
Not implemented under RISC OS
%shmread
Not implemented under RISC OS
%shmwrite
Not implemented under RISC OS
%shutdown
Not implemented under RISC OS
%socket
Not implemented under RISC OS
%socketpair
Not implemented under RISC OS
%symlink
Not implemented under RISC OS
%sysread
Not implemented under RISC OS
%syswrite
Not implemented under RISC OS
%times
Not implemented under RISC OS
%umask
Not implemented under RISC OS
%utime
Not implemented under RISC OS
%wait
Not implemented under RISC OS
%waitpid
Not implemented under RISC OS
%atan2(X,Y)
returns arctangent X/Y in the range -pi to +pi
%caller
caller(EXPR)
caller EXPR
caller returns stack frame
information as:-
($package, $filename, $line) = caller
EXPR (if present) is number of stack
frames to rise through
%chdir
chdir(EXPR)
chdir EXPR
chdir
changes CSD to EXPR if possible.
With no parameter changes to root of
default drive.
Returns 1 for succes or 0 for failure.
%chop
chop(LIST)
chop(VARIABLE)
chop VARIABLE
chop
chops the last character from a string and returns the
character removed.
With no variable chops $_.
Given a list chops each item of the list and returns
the (former) last character of the last item.
Lvalues may be chopped:-
$answer=chop(<STDIN>);
%close
close(FILEHANDLE)
close FILEHANDLE
closes a file or pipe and resets the line counter ($.)
Closing a pipe waits for the pipe to exit and sets $?.
FILEHANDLE may be an expression evaluating to
a real filehandle name.
%closedir
closedir(DIRHANDLE)
closedir DIRHANDLE
closes a directory opened by opendir
%cos
cos(EXPR)
cos EXPR
returns cosine of EXPR (taken as radians)
%dbmclose
dbmclose(ASSOC_ARRAY)
dbmclose ASSOC_ARRAY
breaks the binding between a dbm file and
an associative array
%dbmopen
dbmopen(ASSOC_ARRAY,DBNAME,MODE)
binds ASSOC_ARRAY to dbm file called DBMNAME
uses GNU dbm package and is believed to be
rather slow.
%defined
defined(EXPR)
defined EXPR
EXPR is an lvalue thus
print "$val\n" while defined($val = pop(@ary));
is perfectly valid;
returns 1 if EXPR has a defined value, 0 otherwise
packages may be checked for
die "No XYZ" unless defined %_XYZ;
%delete
delete $ASSOC{KEY}
deletes the specified value from the specified
associative array.
If the array is bound to a dbm file then deletes
the corresponding entry.
%die
die(LIST)
die LIST
die
i) Outside an eval
prints the concatenated LIST to STDERR and exits
with the current value of $! unless $! is 0 in
which case ($? >> 8) is used to allow for
`commands`.
With no LIST uses "Died".
If the LIST does not have a terminal newline
the die function appends the script filename,
line number, and input line number (if any), with a
newline.
ii) Within an eval
as above except that the $@ variable contains the
string that would have been output on STDERR, the
eval is aborted and itself returns the undefined
value.
%do
do BLOCK
do SUBROUTINE(LIST)
do EXPR
i) The do BLOCK form returns the value of the last
command in the enclosed sequence. When modified by
a loop modifier, e.g.
do { ... } unless CONDITION
the BLOCK is executed at least once before the
CONDITION is tested.
ii) The do SUBROUTINE(LIST) is a subroutine
invocation. The brackets are essential (even with an
empty list) to disambiguate this from the do EXPR
form. SUBROUTINE may be a simple scalar variable
containing the name of a subroutine to call. The
arguments are always evaluated in an array context.
The alternative (and generally recommended) form is
&SUBROUTINE(LIST)
in this form the parentheses are optional if the
list is empty in which case the @_ array is not
passed to the subroutine.
iii) The do EXPR form should be considered as an
obsolescent version of the requires operator which
should be preferred in new code.
%each
each(ASSOC_ARRAY)
each ASSOC_ARRAY
returns a two element list, ($key,$value), formed
from the next value of the associative array. On
exhausting the associative array returns a null
array before starting again on the next call. The
iterator can be reset only by reading all of the
elements and the array must not be modified while
iterating over it. The iterator is shared with the
keys() and values() functions for any given
associative array. Is not too clever in Perl v3.0
and should not be pushed too hard.
%eof
eof(FILEHANDLE)
eof()
eof
Returns 1 if the next read on FILEHANDLE will
return eof or if the file is closed. Uses ungetc so
is useless in an interactive context. A bare eof
refers to the last file read (and therefore
distinguishes individual files within the @ARGV
pseudo file. eof() on the other hand would return
true only for the last file in the @ARGV stream.
%eval
eval(EXPR)
eval EXPR
eval
The value returned by EXPR is parsed and executed as
a perl program within the context of the current
program. The eval text is a block so variables may
be localised. Eval returns the undefined value if
there were any syntax or runtime errors with the
error string in $@. Otherwise a null string is
guaranteed to be returned in $@ with the eval
returning the value of the last expression
evaluated. $_ will be evaluated if no parameter is
given. The parameter itself does not need to contain
a terminal semicolon. A simple perl shell is formed
by
while (<>) { eval; print $@; }
%exec
exec(LIST)
exec LIST
replaces the current perl program with the program
specified in list. Therefore exec never normally
returns. If it does it returns false and $! should
be checked for an indication of what went wrong.
Note that exec does not flush any buffers so the
value of $| may need to be adjusted to avoid lost
output.
%exit
exit(EXPR)
exit EXPR
Exits immediately with the specified value. Note
that exit cannot be trapped, therefore die is better
used within subroutines.
%exp
exp(EXPR)
exp EXPR
Returns e to the power of EXPR.
%format
format NAME =
FORMLIST
.
If NAME is omitted it default to STDOUT
FORMLIST is a sequence of lines.
Lines beginning with '#' are treated as comments.
Other lines are picture lines that print literally
apart from picture fields as described below, or
argument lines containing lists of names of variables
whose values will be inserted into the previous
picture line.
Picture fields are:
@<<<<<< left justified field
@>>>> right justified field
@||||||| centred field
@###.## numeric field, point justified
@* a multi-line field (should be alone
on a line)
Picture fields may start with ^ instead of @ in which
case the variable is 'shifted' by the amount
actually used and the remainder is available next
time the variable is referenced. This allows block
filling at the expense of destroying the original
contents of the variable. The string '...' may be used
for the final line of the block in which case '...'
will appear on the output if the variable didn't fit.
Blank lines may be supressed by putting a '~' anywhere
in the line.
Example:
format =
Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
$subject
Index: @<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<
#
## $DESCRIPTION WILL BE DESTROYED
#
$index, $description
Priority: @<<<<<<<<< Date: @<<<<< ^<<<<<<<<<<<<<<<<<<
$priority, $date, $description
From: @<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<
$from, $description
Assigned to: @<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<
$programmer, $description
~ ^<<<<<<<<<<<<<<<...
$description
.
%getc
getc(FILEHANDLE)
getc FILEHANDLE
getc
returns the next character from the file attached to
the filehandle or STDIN if none. Returns a null
string at eof. Very slow, probably only useful in
interactive contexts.
%gmtime
gmtime(EXPR)
gmtime
EXPR gmtime returns a nine element list. Typically
used as
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
=gmtime(time);
note that most of the arrays are zero based. if EXPR
is omitted a£the value returned is as for
gmtime(time).
Under RISC OS 3 the value returned is as contained
in Sys$Time and the $isdst element is zero, so the
time may be BST or GMT.
/* There must be a better way of getting at
this than
do { open(T,"status|"); local(@T)=<T>; grep(/BST/,@T); }
which bit of the CMOS do we read?
where are my RISC OS 3 PRMs??
*/
%goto
goto LABEL
Although a function this does not return a value.
The LABEL must be on a statement in the main body
that is not inside a do {} construct. Present only
for backward compatibility.
%grep
grep(EXPR,LIST)
Evaluates EXPR for each element of LISt and returns
a new list constructed of those elements of LIST for
which EXPR evaluated true. Inside the EXPR, $_
contains the LIST element being considered.
Modifying $_ is supported, but will have
unpredictable results if LIST is not a named array.
If evaluated in a scalar context returns the number
of times that EXPR evaluated true. EXPR may, of
course, be an arbitrarily long 'do {BLOCK}'.
%hex
hex(EXPR)
hex EXPR
returns the decimal value of EXPR treated as a hex
string. Use oct for strings that might start 0 or
0x. Spintf can be used for the reverse,
$number=hex("ffff12c0"), sprintf("%lx",$number)
%index
index(STR,SUBSTR,OFFSET)
index(STR,SUBSTR)
Returns the position of the first occurence of
SUBSTR in STR. If OFFSET is specified, searching
commences there. OFFSETs run from 0 unless $[ is
altered. If SUBSTR is not found, $[-1 is returned,
usually -1.
%int
int(EXPR)
int EXPR
Returns the integer portion of EXPR.
%join
join(EXPR,LIST)
Returns a string formed by joining the separate
strings of LIST into a single string with fields
separated by the value of EXPR.
%keys
keys(ASSOC_ARRAY)
keys ASSOC_ARRAY
Returns a normal array containing all the keys of
the associative array. With associative arrays bound
to dbm files the resulting array could be very
large, in which case the use of 'each' and handling
the keys one at a time might be preferable.
%kill
kill EXPR
Raises the signal represented by EXPR (which should
evaluate to an integer or a signal name). Signals
are:-
ABRT 1 /* abort */
FPE 2 /* arithmetic exception */
ILL 3 /* illegal instruction */
INT 4 /* attention request from user */
SEGV 5 /* bad memory access */
TERM 6 /* termination request */
STAK 7 /* stack overflow*/
USR1 8
USR2 9
SERROR 10
Only SIGINT (Escape) is likely to be worth raising
or trapping
%length
length(EXPR)
length EXPR
returns the length in characters of EXPR
%local
local(LIST)
LIST must be composed of legal lvalues. The elements
of LIST are then declared to be local to the
enclosing block, subroutine, eval, or require. The
LIST may be assigned if desired: a common idiom for
naming parameters to sub-routines (and changing
call-by-reference to call-by-value at the same time.
local($min,$max) = @_
%localtime
localtime(EXPR)
similar to gmtime, but supposed to return a time
corrected for the local time zone. Unlikely to be
any different under RISC OS.
%log
log(EXPR)
log EXPR
returns log base e of EXPR
%lstat
lstat(FILEHANDLE)
lstat FILEHANDLE
lstat EXPR
should return the same value as stat on a system
without symbolic links. However, appears to be
undefined in this port.
%mkdir
mkdir(FILENAME)
mkdir FILENAME
creates a directory with the specified name. Returns
1 for success, 0 for failure. If the return is 0, $!
should be set.
%oct
oct(EXPR)
oct EXPR
returns the decimal value given by interpreting EXPR
as an octal string. If EXPR starts "0x" it will be
taken as hex instead. To handle a general numeric
$val = oct($val) if $val =~ /^0/;
The inverse can be achieved with
sprintf("%lo", $number)
%open
open(FILEHANDLE,EXPR)
open(FILEHANDLE)
open FILEHANDLE
opens the file whose filename is given by EXPR and
places the filehandle in FILEHANDLE. If filename is
not given it is assumed to be held in the scalar
variable of the same name as FILEHANDLE. Filenames
may be of the forms:-
"<foo" read (default)
"foo" (as above)
">foo" write
">>foo" append
"+>foo" read/write
"+<foo" (as above)
"|foo" pipe to foo
"foo|" pipe from foo
"-" open STDIN
">-" open STDOUT
[N.B. executables compiled with CLib support redirection
and thus can be opened as pipes. Others can be co-erced
into this behaviour if their name is prefixed with a '%'.
E.g. open(LIB, "%LibFile Lib -l |")
Forgetting this is also a common source of error with
`commands` which also require redirection to work
correctly.]
open returns non-zero for success, the undefined
value otherwise.
Opening an already open file does an implicit close
first, but does not reset the line counter ($.) as
an explicit close would.
Opening involving dup, ">&" etc, is not supported
under RISC OS, neither is "-|" or "|-".
%opendir
opendir(DIRHANDLE,EXPR)
opens the direcxotry specified by EXPR
returns true if succesful
directory and file handles have distinct name sapces.
%ord
ord(EXPR)
ord EXPR
returns the ASCII value of the first character of EXPR
%pack
pack(TEMPLATE,LIST)
returns a string equivalent to a binary structure
encoding the items of LIST as dicated by the
TEMPLATE The TEMPLATE is a string containing one or
more field specifiers of the form '<key><count>'.
The field specifiers may be separated by whitespace
which is ignored. The <key> may be any of
a An ASCII string, null padded
A An ASCII string, space padded
b A bit string, lo-to-hi, vec() compatible
B A bit string, hi-to-lo
h A hex string, low nybble first
H A hex string, high nybble first
c A signed char
C An unsigned char
s A signed short
S An unsigned short
i A signed integer
I An unsigned integer
l A signed long
L An unsigned long
f A single-precision float
d A double-precision float (default for perl)
p A pointer to a string
x A null byte
X Back up a byte
@ Null fill to absolute position
u A uuencoded string
T A 5-byte 2s complement integer
The <count> is a simple repeat count except for a, A
where it is a character length. A count of '*'
means use the rest of the LIST. A missing count is
treated as 1.
POSSIBLE BUG. There is a suspicion that the 'hHbB'
templates are broken.
%pop
pop(ARRAY)
pop ARRAY
removes and retruns the last item of the array. It
has the same effect as
$ARRAY($#ARRAY--)
returns undef if the array was empty
%print
print(FILEHANDLE LIST)
print(LIST)
print FILEHANDLE LIST
print LIST
print
prints the LIST - whcih may be a string or
comma-separated list of strings, to the file
specified by FILEHANDLE. The FILEHANDLE may be
indirect via a simple scalar variable as normal. If
the FILEHANDLE is omitted, uses the currently
selected ouptut stream which will be STDOUT in the
absence of specific select statements. If LIST is
omitted uses $_. Remember that because print expect
a LIST its operands are evaluated in an array
context, thus
print <T>;
will not print a single line from T, but rather the
entire contents of T.
%printf
printf(FILEHANDLE FORMAT, LIST)
printf(FORMAT, LIST)
printf FILEHANDLE FORMAT, LIST
printf FORMAT, LIST
equivalent to
print FILEHANDLE sprintf(LIST);
%push
push(ARRAY, LIST)
Treats array (the '@' is optional) as a stack and
pushes LIST onto the end.
Equivalent to
foreach $value (LIST)
{
$ARRAY[++$#ARRAY] = $value;
}
%rand
rand(EXPR)
rand EXPR
rand
Returns an arbitrary real number between 0 and EXPR
(exclusive). EXPR should be positive. EXPR is taken
as 1 if omitted.
%read
read(FILEHANDLE,SCALAR,LENGTH,OFFSET)
read(FILEHANDLE,SCALAR,LENGTH)
attempts to read LENGTH bytes from FILEHANDLE into
SCALAR. Returns number of bytes actually read, 0 on
eof, undef on failure. If OFFSET is used it
specifies where, in SCALAR, to start placing the
bytes read. Do not intersperse with calls to
sysread() Read may be buffered by the system
%readdir
readdir(DIRHANDLE)
readdir DIRHANDLE
In array context returns all the (remaining) entries
in a directory opened using opendir. In a scalar
context returns the next entry only. If there are no
more gives an empty list (array) or undef (scalar).
%rename
rename(OLDNAME, NEWNAME)
renames the file in question. Returns 1 for success.
Unlike Unix implementations, if NEWNAME already
exists it is not destroyed. Unfortunately, rename
still returns 1 in this instance (as it does if
OLDNAME doesn't exist!).
%require
require(EXPR)
require EXPR
require
includes and executes any Perl code found in the
file whose name is given by EXPR. Require will check
the @INC array to ensure that the code has not
already been included and will update the @INC array
if necessary. require will also use the search path
held in @INC to find the file if necessary.
%reset
reset(EXPR)
reset EXPR
reset
reset EXPR treats EXPR as a list of characters and
resets all variables (including arrays) beginning
with one of those letters. Thus
reset 'a-z';
resets all variables whose names begin with a
lowercase letter. Note that reset 'A-Z' would kill
the ARGV, ENV, INC, and SIG arrays. Resetting an
array bound to a dbm file merely flushes the cache.
For single variables - particularly arrays -
undef(ARRAY) is more efficient.
Reset with no parameter resets ?? searches so that
they match again.
The scope of a either type of reset is confined to
the current package.
Reset always returns 1.
%return
return LIST
returns from a subroutine with the value specified.
Illegal outside subroutines.
Allowing an implicit return of the last expression
evaluated is more efficient.
%reverse
reverse(LIST)
reverse LIST
In an array context returns an array containing the
elements of LIST in the opposite order. It is
implemented fairly efficiently.
It can also invert associative arrays
%VNE = reverse %ENV
In a scalar context returns a string consisting of
the first element of LIST in reverse order.
%rewinddir
rewinddir(DIRHANDLE)
rewinddir DIRHANDLE
causes the next use of readdir() on the DIRHANDLE to
return the first (scalar context) or all (array
context) entries in the directory specified once
again.
%rindex
rindex(STR,SUBSET,OFFSET)
rindex(STR,SUBSET)
works a index does except that it returns the
position of the last occurence of of SUBSTR in STR.
OFFSET, if specified, is the rightmost position that
may be returned.
%rmdir
rmdir(FILENAME)
rmdir FILENAME
Deletes the directory specified by FILENAME if it
exists and is empty when it returns 1. Otherwise it
returns 0 with an error code in $!.
%s
s/PATTERN/REPLACEMENT/[g][i][e][o]
searches a string for the pattern, if found replaces
that pattern with the replacement text, and returns
the number of replacements made. Only the first
occurence is replaced unless the g (global)
modifiers is used. The i modifier causes
case-insensitive behaviour. The e modifier means
that REPLACEMENT will be treated as an expression
rather than as a string. Additional 'e's may be
specified to cause additional evaluation of the
resulting string. The pattern is also subject to
variable interpolation as strings usually are. The o
modifier may be used to indicate once-only
evaluation of the string where the interpolated
variables will not change over the life time of the
substitution and may be a valuable optimization in
loops. The o modifier has no effect if there are no
variables in the pattern.
Any non-alpahanumeric may be used instead of the
'/'s. In particular single quotes prevent
interpretation of the replacement text (this is,
however, over-ridden by the e modifier). If
backquotes are used, the replacement string is a
command whose result will be used as the replacement
text.
If no other string is specified using the =~ or !~
operators, then $_ is searched and modified. The
string specified must be an lvalue.
Forgetting that the second subpattern is specified
as \2 within the pattern but $2 within the
replacement is a common error. (As is thinking that
\0 is the first sub-pattern because of contact with
brain-dead editors such as !Edit or !SrcEdit). \0 is
a null, \1 is the first subpattern.
%scalar
scalar(EXPR)
A pseudo function forcing EXPR to be evaluated in a
scalar context rather than in an array context.
Useful, therefore, when EXPR is to be used as an
element of a list.
Not using scalar in operations such as
local($nextline) = scalar(<STDIN>);
is a common error. The argument of local is a list.
Assignment to a list is an array operation. Thus
<STDIN> would be in an array context resulting in a
read to eof rather than eol were it not for the use
of scalar.
%seek
seek(FILEHANDLE,POSITION,WHENCE)
positions the file pointer for FILEHANDLE as
specified. WHENCE specifies what POSITION should be
taken as relative to: 0 for beginning, 1 for current
position, 2 for end of file. POSITION is thus >=0 if
WHENCE is 0, <=0 if WHENCE is 2, and positive or
negative for a WHENCE of 1.
seek returns 1 for success and 0 for failure.
seek is useful for resetting eof on dynamic files,
e.g.
for (;;) {
while (<FILE>) {
print;
}
sleep 5;
seek(FILE,0,1) # Seek to the current poistion in
the file # thus clearing the eof error }
which would print out lines as they were added *IF*
RISC OS allowed writing to files open for reading
elsewhere. Boring, or what.
%seekdir
seekdir(DIRHANDLE,POS)
Sets the current position for the readdir() routine.
On some systems POS must be a value returned by
telldir(), but under RISC OS integers 0 .. n appear
to be fine.
%select
select(FILEHANDLE)
select
select(RBITS,WBITS,EBITS,TIMEOUT)
The first form returns the currently selected
filehandle and sets it if FILEHANDLE is supplied.
The currently selected filehandle is significant to
'write' or 'print' when used without a filehandle.
Special variables related to output also refer to
the current filehandle.
Subroutines should ideally exit with the selected
filehandle unaltered. Since FILEHANDLE may be an
expression evaluating to a filehandle it is not
difficult to do a save and restore.
Which leads to one of Larrys' favourite bits of
bizarre Perl: setting stderr unbuffered while
leaving the current filehandle unaltered.
select((select(STDERR), $| = 1)[$[])
The second form of select (which has nothing to do
with the first) is not implemented under RISC OS
%shift
shift(ARRAY)
shift ARRAY
shift
returns the first element of an array and shortens
the array by one element from the left. Without
arguments operates on @ARGV in the main program and
@_ in subroutines. If the array has no elements it
returns the undefined value.
%sin
sin(EXPR)
sin EXPR
returns the sine of EXPR (taken as radians).
%sleep
sleep(EXPR)
sleep EXPR
sleep
suspends the script for EXPR seconds.
If EXPR is omitted sleeps forever!
On some systems sleep may be interrupted by a signal
and suitable handler, but under RISC OS a SIGINT
appears to bypass the handler if the script is
sleeping, so the script just terminates.
syscall() and suitable swis would need to be used
instead.
returns the number of seconds actually slept. This
may be a lot longer than the number asked for if
RISC OS has its attention distracted in the meantime
(e.g. by a non-wimp task).
%sort
sort(SUBROUTINE LIST)
sort(LIST)
sort SUBROUTINE LIST
sort LIST
sorts the list and returns a sorted array. If
SUBROUTINE is omitted soes a string comparison sort.
SUBROUTINE, if specified, is the name of a
subroutine that will return -1, 0, or 1, when
presented with two elements.
For efficiency reasons, SUBROUTINE is not called in
the normal way. It may not be recursive, @_ is not
used, the two parameters are passed by reference as
$a and $b.
If SUBROUTINE is a simple scalar variable this
should evaluate to the name of the actual subroutine
to use.
sub numerically { $a <=> $b; }
@sortednumerically = sort numerically 53,29,11,32,7;
note that
sort reverse @a
is equivalent to
reverse sort @a
because of the way that lists work.
%splice
splice(ARRAY,OFFSET,LENGTH,LIST)
splice(ARRAY,OFFSET,LENGTH)
splice(ARRAY,OFFSET)
removes the elements of ARRAY designated by OFFSET
and LENGTH and replaces them with LIST if LIST is
provided. OFFSET may be negative in which case it is
reckoned from rigyt to left. Returns the elements
removed. The array shrinks or grows as needed. If
LENGTH is omitted everything from OFFSET onwards is
removed. Note the following equivalencies:
push(@a, $x, $y) splice(@a, $#a+1, 0, $x, $y)
pop(@a) splice(@a, -1)
shift(@a) splice(@a, 0, 1)
unshift(@a, $x, $y) splice(@a, 0, 0, $x, $y)
$a[$x]=$y splice(@a, $x, 1, $y)
%split
split(/PATTERN/,EXPR,LIMIT)
split(/PATTERN/,EXPR)
split(/PATTERN/)
split
splits the string specified by EXPR into an array of
strings which it returns. If EXPR is omitted, split
uses $_. The pattern matches the delimiters
separating the sub-strings. The delimiters are not
returned.
In a scalar context splits into @_ and returns the
number of substrings. In an array context the split
can be forced into @_ by using ?? as the pattern
delimiters (but the array value is still returned).
If PATTERN is elided the split is on whitespace: /[
\t\n]+/ PATTERN may match more than one character.
If the match fails the original string is returned.
If a LIMIT is specified the split is into no more
than LIMIT fileds. If LIMIT is unspecified any
trailing null fileds are stripped.
If PATTERN can match the null string then the split
is into individual characters at that point.
join(':', split(/ */,'hi there'));
returns "h:i:t:h:e:r:e". Notice that the space -
which matched as a delimiter - is not returned as
is the norm for delimiters.
LIMIT is widely used for partial splitting, as in
($command,$flags,$filelist)=split(/[ \t]+/,$_,3);
In the case of assignment to a list if a LIMIT is
not given a limit of one greater than the number of
elements in the list is actually used. Splitting
into more fields than are needed should be avoided
for efficiency.
If the delimiters are required, then parentheses
should be used in the pattern round those
delimiters wanted
split(/(-)|,/, '1-10,20');
produces
(1,'-',10,20)
The /PATTERN/ argument may be replaced with a
variable as /$pattern/, in this case the o modifier
may be used for invariant patterns /$pattern/o
A literal space replacing the whole of PATTERN
splits on whitespace but ignores leading
whitespace. These are all subtley different:-
split or split(/[ \t]+/) splits on whitespace, leading space gives null fields
split(' ') splits on whitespace, no leading null fields
split(/ /) split on literal single space, may give nulls
%sprintf
sprintf(FORMAT,LIST)
returns a string which is created from LIST using
the supplied FORMAT. The FORMAT is a string
containing fileds of the approximate form %m.nx,
one per element of the list to be used.
The m is the minimum field length, -ve for left
justified, padding is done with zeroes for numbers
and spaces for non-numerics.
The n is typically a maximum length or a precision
for exponential formats.
The x is one of:-
s string
c character
d decimal number
ld long decimal number
u unsigned decimal number
lu long unsigned decimal number
x hexadecimal number
lx long hexadecimal number
o octal number
lo long octak number
e exponential fp
f fixed point fp
g compact fp
%sqrt
sqrt(EXPR)
sqrt EXPR
returns the square root of EXPR. Returns the largets
possible -ve number if asked for the square root of
a negative quantity.
%srand
srand(EXPR)
srand EXPR
sets the random number seed with the value of EXPR.
If EXPR is omitted does srand(time) which may be
fairly predictable.
%stat
stat(FILEHANDLE)
stat FILEHANDLE
stat(EXPR)
returns an eight element array
($found,$filetype,$loadaddress,$execaddress,$length,$attributes,$ts1,$ts2)
=stat($file);
$found is 0 for not found, 1 for a file, and 2 for a
directory
$ts1 is a RISC OS 5-byte time (see the P key to
unpack), i.e. centiseconds from 00:00:00.00 1/1/1900
$ts2 is Unix format, i.e.seconds from 00:00:00 1/1/1970
%study
study(SCALAR)
study SCALAR
study
builds an index for SCALAR ($_ if unspecified). This
can result in speed enhancement if many pattern
matches are to be done against the string. It
carries the overhead of building the index so may or
may not be faster overall. Short constant string
searches benefit most, but not if they are anchored.
Only one study may be active at a time. A new study
forgets the older one.
For strings not known till runtime, search loops can
be built as strings and then 'eval'ed. Together with
setting $/ to input entire files as single records
(given the memory ;-) this can be extremely fast.
%substr
substr(EXPR,OFFSET,LENGTH)
substr(EXPR,OFFSET)
extracts a substring from EXPR and returns it.
OFFSET runs from $[, normally 0
If OFFSET is negative it is a character length from
the right of the string If LENGTH is omitted
everything to the end of the string is returned.
substr() can be an lvalue if EXPR is also an lvalue.
In this case the string may grow or shrink if if
LENGTH is not the same as the length of the item
assigned.
%syscall
syscall(LIST)
syscall LIST
Normally called with LIST containing
($swi_name_or_number, $r0, ..., %$r9)
the swi specified is called with the remaining
values placed in the registers. Only as many
registers as are needed need be specified.
If $rn is a number it is used directly, if it is a
string a pointer to the string is passed.
Care should be taken because of Perl's tendency to
convert numbers to strings and vice versa. Use
$rn+0 to ensure a numeric interpretation and $rn.''
to ensure a string interpretation in cases of
doubt.
Obviously if values are returned in strings the
caller must ensure that the string is large enough
to accept the return value.
Buffers may be created as
$buffer='\0' x 512; # A 512 byte null filled buffer
or
$buffer=pack("x512",'') # Another one.
Generally with strings used for return values,
call-by-reference is wanted. NOT call by value, so
be careful with assignments, particularly in
subroutines.
Actual pointers can be obtained by using
$pointer=unpack("I",pack("p",$buffer))
though the use to which such 'pointers' are put is
at the users's risk! Pointer comparison is known to
be ok, and some pointer arithemetic, eg
$end_of_buffer=unpack("I",pack("p",$buffer))+length($buffer);
for those awkward little swis that want start and
end rather than start and length.
Syscall returns either a null string (in the case of
errors) in which instance $! may be diagnostic or a
packed structure containing ARM registers R0 to R9.
(@reg[0..8],$flags)=unpack('I10', syscall("Wimp_Initialise", @reg));
%system
system(LIST)
system LIST
attempts to have the sytem execute LIST. Returns
unlike exec. The value returned should be zero for
success and -ve for failure but this isnot
completely consistent under RISC OS. $! will hold
the error, if any.
%tell
tell(FILEHANDLE)
tell FILEHANDLE
tell
Returns the position of the file pointer (in bytes).
FILEHANDLE may be an expression evaluating to a
file handle. If FILEHANDLE is omitted, tell targets
the last file read. tell() has no meaning for
devices or pipes.
%telldir
telldir(DIRHANDLE)
telldir DIRHANDLE
Returns the current position of readdir() on
DIRHANDLE. May be used as a parameter to seekdir()
%time
time
This function returns the number of seconds since
1/1/1970.
%tr
tr/SEARCHLIST/REPLACEMENTLIST/[c][d][s]
y/SEARCHLIST/REPLACEMENTLIST/[c][d][s]
SEARCHLIST and REPLACEMENTLIST are placed in a
one-to-one correspondence. If REPLACEMENTLIST is
shorter than SEARCHLIST then the last character of
REPLACEMENTLIST is repeated as necessary (except
with the d option). If REPLACEMENTLIST is null a
copy of SEARCHLIST is used (except with the d
option).
The function replaces all characters in SEARCHLIST
with their corresponding character from
REPLACEMENTLIST. The returned value is the number of
replacements made.
The c option complements SEARCHLIST: in effect the
SEARCHLIST given is removed from the range \001-\377
and the result used as SEARCHLIST.
The d option deletes all characters within
SEARCHLIST that are not found in REPLACEMENTLIST.
The s option causes any substitutions that would
result in multiple identical REPLACEMENTLIST
characters being output to be replaced by a single
occurence of that character.
y is a synonym for tr.
If no string is specified via =~ or !~ the $_ string
is used. The string specified must be an lvalue.
%truncate
truncate(FILEHANDLE,LENGTH)
truncate(EXPR,LENGTH)
This function does not appear to be implemented in
the current port.
%undef
undef(EXPR)
undef EXPR
undef
Makes the value of EXPR (which must be an lvalue)
undefined. Subroutine names should be prefixed with
'&'. Storage is recovered, so undeffing large arrays
when they are finished with can make smaller tasks.
The function always returns the undef value. The
principal use of undef with no argument is as an
error return from subroutines.
%unlink
unlink(LIST)
unlink LIST
Equivalent to *remove - i.e. tries to delete the
files named, but does not provoke an error if it
cannot. unlink() will not delete directories (unless
Perl is started with the -U flag). Use rmdir()
instead.
%unpack
unpack(TEMPLATE,EXPR)
Almost the reverse of pack(), except that some
templates make no sense when packing, others make no
sense when unpacking.
EXPR is a string representing a structure and unpack
unpacks this into an array according to the pattern
given in TEMPLATE.
Keys recognized in TEMPLATE are
a An ASCII string, unstripped
A An ASCII string, trailing spaces and nulls stripped
b A bit string, lo-to-hi, vec() compatible
B A bit string, hi-to-lo
h A hex string, low nybble first
H A hex string, high nybble first
c A signed char
C An unsigned char
s A signed short
S An unsigned short
i A signed integer
I An unsigned integer
l A signed long
L An unsigned long
f A single-precision float
d A double-precision float (default for perl arithmetic)
p A pointer to a string
x Skip forward a byte
X Back up a byte
@ Go to absolute position in string for next field, @* is end of string
u A string to uudecode
T A 5-byte 2s complement integer
P A pointer to a string whose length is given in the count.
P is not recognized in pack() as there is
no way to ensure the exact length of the string.
Reads exactly count bytes from the string pointed
to, regardless of what these bytes are (p1 would
stop at a \0).
The <count> is a simple repeat count except for a, A
where it is a character length. A count of '*'
means use the rest of the LIST. A missing count is
treated as 1.
Prefixing a TEMPLATE field with %<num> means that
you want a <num>-bit checksum
of the item rather than the item itself.
POSSIBLE BUG: There is a suspicion that the 'hHbB'
templates are broken
%unshift
unshift(ARRAY,LIST)
Does the opposite of a shift().
It attaches LIST to the front of array ARRAY and
adjusts the length of ARRAY as needed.
%values
values(ASSOC_ARRAY)
values ASSOC_ARRAY
returns a normal array consisting of all the
valuesin the named associative array. Using values
on an array bound to a dbm file can produce huge
arrays.
%vec
vec(EXPR,OFFSET,BITS)
treats the string which EXPR evaluates to as an
array of bits (the conversion is as unsigned
integers). The OFFSET is the number of *elements* to
skip over (not the number of bits), BITS is the
number of bits in each element.
BITS must be one of 1,2,4,8,16,or 32.
The ordering is such that vec($string,0,1) is the
lowest bit of the first byte of $string.
(IE. the ordering is 32107654ba98fedc
where 0-f represent 0-15)
A true bit vector (i.e. with BITS=1) can be
translated to/from strings of 1s and 0s by using a
b* template with pack() and unpack().
vec() may be used as an lvalue to set specific bits
Note that EXPR is a scalar and will be
irredeemably treated as the printed representation
of EXPR. Thus vec(0xff,... will return a bit
string related to 0x323535 - i.e. the character
string '255'.
This limits its usefulness somewhat.
%wantarray
wantarray
This pseudo function returns true if the current
context is looking for an array and false if it is
looking for a scalar. Typical use
return wantarray ? () : undef;
%warn
warn(LIST)
warn LIST
Similar to die() but doesn't exit.
E.g.
warn "Debugging enabled" if $debug
%write
write(FILEHANDLE)
write(EXPR)
write
writes a formatted record to the specified file
using the format established for that file. By
default that is the format with the same name as the
FILEHANDLE, but the format for the current
filehandle may be explicitly set with $~.
The default top-of-page format has the same name as
the format with _TOP appended, but may be set using
$^
The number of lines left on a page is held in $-
which can be set to 0 to force a new page for the
next write() which will be done automatically if
there is insufficient room for the next record.
%$_
$_ Default input, parameter, and pattern
%$.
$. Current input line on last filehandle read
%$/
$/ Input record separator, newline by default
%$,
$, Output field separator for print operator
%$"
$" Separator for array elements interpolated
in strings
%$\
$\ Output record separator for print operator
%$#
$# Output format for numbers, default "%.20g"
%$*
$* If set to 0 (default) assume in pattern
matching that strings contain only a single
line. If set to 1, strings will be matched as
if they might contain multiple lines.
%$?
$? Status return from last `command`, pipe, or
system operator.
%$]
$] Perl version string
%$[
$[ Index of first elements in arrays. Default 0.
%$;
$; Subscript separator for multi-dimensional
array emulation. Default \034
%$!
$! As a number evaluates to an error no. As a string
evaluates as the last error string.
I.e. set to the value of _kernel_last_oserror
whenever an OS call returns an error.
%$@
$@ Perl error message from last eval, require, etc
%$:
$: The set of characters on which strings may be
broken in '^' fields of formats.
Default ' \n-'
%$0
$0 The name of the file containing the script
being executed.
%$$
$$ Not implemented under RISC OS
%$<
$< The pathname of the CSD when Perl started
Note, under Unix this would the real uid
%$>
$> The pathname of the current CSD
Note, under Unix this would be the effective uid
%$(
$( Not implemented under RISC OS
%$)
$) Not implemented under RISC OS
%$^T
$^T The time (in time() format) when the script
began execution
%$%
$% Curent page number on currently selected output
%$=
$= Page length of currently selected ouput.
Default 60
%$-
$- Number of lines left on current page
%$~
$~ The name of the report format for the currently
selected output channel
%$^
$^ The name of the top of page format on the
current output channel
%$|
$| If set non-zero forces flushing of buffers
after every write or print on the selected
output channel. Default is 0.
%$ARGV
$ARGV Current file name when reading from <>
%$&
$& String matched by last pattern match
%$`
$` String preceding match in last pattern
%$'
$' String following match in last pattern
%$+
$+ The portion of the string matched by the last
bracket in the last pattern
%@ARGV
@ARGV array containing command line arguments
%@INC
@INC array containg places to search for scripts
%@_
@_ Parameter array in subroutines. Used by split()
in scalar contexts.
%ENV
ENV Contains the current environment. May be written
to set variables, but is read at script
initialisation only - i.e. variables
set/altered by other tasks after the script
started will not be reflected in %ENV.
%INC
INC List of files that have been 'require'-d.
%SIG
SIG Array containing signal handlers. A signal
handler may be installed by putting the name
of a subroutine in the appropriate element.
Help for kill() has a list of signals.
The tokens 'IGNORE' and 'DEFAULT' are also
valid in this array.
%FILE
__FILE__
Token containing current filename. Returns (eval)
inside evals. May not be interpolated in strings.
%LINE
__LINE__
Line number in current script. May not be
interpolated in strings. Returns null string in
evals.
%END
__END__
Everything after this token is ignored by the parser
but may be accessed via filehandle <DATA>.
%<<
<<STRING
'here-is' text quoting.
All following lines up to a line starting and
containing STRING alone are effectively inserted
at the identified place. If quotes are used in the
first instance the following lines are treated
accordingly.
>>EOF
>>"EOF"
The lines are used after string interpolation
>>'EOF'
The lines are used literally
>>`EOF`
The lines are executed as commands
%re
Regular Expressions
1. Regular expressions may be separated
by '|' to express alternatives.
The '|' has a lower precedence than
anything else.
2. Regular expressions surrounded by ()
match whatever the enclosed expression
matches.
3. Assertions are:-
^ start of string (line if $* set)
$ end of string (line if $* set)
\b word boundary (except inside '[]' where it
is a backspace character)
\B not a word boundary
assertions match on the 'gaps' between characters
4. Quantified atoms are atoms followed by a quantifier.
Quantifiers are:-
{n,m} must occur at least n and not more than m times
{n,} must occur at least n times
{n} must occur exactly n times
* 0 or more times - {0,}
+ 1 or more times - {1,}
? 0 or 1 times only - {0,1}
5. Atoms are:-
\0 matches null
\nn or \nnn matches the ASCII character whose
octal code is nn or nnn.
\xnn matches the ASCII character whose code
in hexadecimal is nn.
\cx where x is a single character matches
the corresponding control character,
thus \cI and \x09 are equivalent atoms.
\\ matches \
\b matches backspace, but only if inside a
character class '[]'.
A list of characters in square brackets, [],
matches any character in the brackets. If the
first character is '^' the match is for any
character not in the brackets. If ']' is needed
as a character it must be the first character
(or second after '^'). If '^' is needed as a
character it must not be first.
Ranges may be used by inserting '-' between
two characters. '\-' may be used to prevent
this interpretation of hyphen.
. matches any character except \n
\n newline
\r carriage return
\t tab
\f formfeed
\d a digit [0-9]
\D a non-digit [^0-9]
\w an alphanumeric [0-9A-Z_a-z]
\W a non-alphanumeric
\s a whitespace [ \t\n\r\f]
\S a non-whitespace
Any character not previously mentioned
matches itself.
Any character preceded by a backslash and not
mentioned above matches itself.
\1, \2, \3, .. are backreferences and match
whatever the 1st, 2nd, 3rd, parenthesised
expression matched.
%op
Operators, from lowest to highest precedence
1. list operators, nonassociative.
2. , left assoc., expression separator as C
e.g. <EXPR1>,<EXPR2> has the value <EXPR2>
3. = right assoc., assignment
There are a host of assignment operators,
+= -= *= /= %= |= &= ^= >>= <<= **= .= x=
4. ?: right assoc., conditional operator as C
<CONDITION> ? <EXPR_T> : <EXPR_F>
has value <EXPR_T> if <CONDITION> is true
(non-zero, non-null, & defined) and <EXPR_F>
otherwise.
5. .. nonassoc., range operator.
In array context returns an array of values from
its left value to its right value.
@digits = (0..9)
@alphabet = ('A'..'Z')
In scalar context returns a boolean value. This is
false as long as the left value is false, then true
until the right value becomes true after which it
returns false again. While returning false the
right value is not evaluated and contrariwise
while returning true.
The 'true' value returned is actually a sequence
number from '1' up to 'nnE0' (the E0 does not
affect the numeric value, but makes the last item
easier to check for).
If either (or both values) are static numbers an
implicit comparison with $. (the current input line
number) is done.
6. || left assoc., logical or
7. && left assoc., logical and
8. | left assoc., bitwise or
^ left assoc., bitwise eor
9. & left assoc., bitwise and
10. == nonassoc., numeric equality
!= nonassoc., numeric inequality
<=> nonassoc., numeric comparison,
returns -1, 0, 1
eq nonassoc., string equality
ne nonassoc., string inequality
cmp nonassoc., string comparison
11. < nonassoc., numeric less than
> nonassoc., numeric greater than
<= nonassoc.,
>= nonassoc.,
lt nonassoc., string less than
gt nonassoc., string greater than
le nonassoc.,
ge nonassoc.,
12. named unary operators nonassoc.,
13. file test operators nonassoc.,
-Z EXPR
EXPR is a filename or filehandle. $_ is used
if EXPR is omitted (except -t which uses STDIN).
If _ is used as the EXPR then the information
from the last test is used (which saves another
statand is much more efficient).
-r/-R file is readable/publicly readable
-w/-W file is writeable/publicly writeable
-e/-z/-s file exists/has zero/has non-zero size
-f/-d file is a plain file/directory
-t filehandle is a terminal
-T/-B filename (not handle) is text/binary
this is based on an opinion formed
by examining the first few blocks.
both return true on null files. Both
return false on directories.
-A file time stamp test. Returns difference
in age between file and time program
started as given by $^T and measured
in days. Presumably can be negative
for files created after the program
started.
Note that for directories this will use the
actual 'creation on disc' date as returned
by INFO and not the date displayed by Filer.
-L file is locked
14. << left assoc., bitwise shift left
>> left assoc., bitwise shift right
15. + left assoc., addition
- left assoc., subtraction
. left assoc., string concatenation
16. * left assoc., multiplication
/ left assoc., f.pt. division
% left assoc., modulo division
x left assoc., string reproduction
17. =~ left assoc., pattern binding operator
!~ left assoc., negated pattern binding
18. ! right assoc., negation operator
- right assoc., unary minus
~ right assoc., bitwise NOT
19. ** right assoc., exponentiation operator
20. ++ nonassoc., string or numeric autoincrement
-- nonassoc., numeric autodecrement
21. '(' left assoc., functions and parenthesis
%glob
File globbing is supported if Glob is found on the Run$Path.
The RISC OS standard is followed
* any number of characters
# any single character
%mode
$Mode
The current screen mode. Can be assigned to.
%Rows
$Rows
Screen rows currently available
%Cols
$Cols
Screen columns currently available
%osrdch
&osrdch()
returns a single character string from OS_ReadC
%oswrch
&oswrch(INT)
writes the character whos ASCII code is INT
using OS_WriteC. Returns 1 for success, undef for
failure.
%osrdstr
&osrdstr(LEN,LO,HI)
reads a string using OS_ReadLine. Uses a buffer of
length LEN characters to hold it internally. LO and
HI are boundaries on the codes accepted, default
32 and 255. Returns the string.
%oswrstr
&oswrstr(STR)
writes STR to the screen. STR may contain control
characters which will be interpreted as VDU codes,
e.g. &oswrstr("\026\000") changes to mode 0. Returns
1 for success, undef for failure.
%fx
&fx(NUM,X,Y)
peforms OS_Byte call NUM with the given X and Y
values. Returns an integer whose bottom byte is
R1, second byte R2, third byte 0 or 1 as carry was
clear or set, and fourth byte 0.